---
title: "Tree Data"
enterprise: true
---

Use Tree Data to display data that has parent / child relationships where the parent / child relationships are provided
as part of the data. For example, a folder can contain zero or more files as well as other folders.

This section introduces simple ways to work with Tree Data, before covering more advanced use cases.

## Tree Data Mode

In order to set the grid to work with Tree Data, simply enable Tree Data mode via the Grid Options using:

```js {% frameworkTransform=true %}
const gridOptions = {
    treeData: true
}
```

## Supplying Tree Data

When providing tree data to the grid, you will need to implement the `gridOptions.getDataPath(data)` callback to tell the grid the hierarchy for each row. The callback must return a `string[]` representing the route, with each element specifying a level of the tree. Below are two examples presenting the hierarchy in different ways.

{% apiDocumentation source="grid-options/properties.json" section="rowGrouping" names=["getDataPath"] /%}

```js
// sample hierarchy, Malcolm is child of Erica
// + Erica
//   - Malcolm

// ############
// Example #1 - hierarchy in the data is already a string array
// ############
const rowData = [
    { orgHierarchy: ['Erica'], jobTitle: "CEO", employmentType: "Permanent" },
    { orgHierarchy: ['Erica', 'Malcolm'], jobTitle: "VP", employmentType: "Permanent" }
    ...
]
// just return the hierarchy, no conversion required
getDataPath: data => {
    return data.orgHierarchy;
}

// ############
// Example #2 - hierarchy is a path string, needs conversion
// ############
const rowData = [
    { path: "Erica", jobTitle: "CEO", employmentType: "Permanent" },
    { path: "Erica/Malcolm", jobTitle: "VP", employmentType: "Permanent" }
    ...
]
// callback converts "Erica/Malcolm" to ["Erica","Malcolm"]
getDataPath: data => {
    return data.path.split('/'); // path: "Erica/Malcolm"
}
```

## Configuring Group Column

There are two ways to configure the Group Column:

* **Auto Column Group** - this is automatically selected by the grid when in Tree Data mode, however you can override the default.

* **Custom Column Group** - you can provide your own custom column group definition, which gives allows more control over how the Group Column is displayed.

### Auto Column Group

When the grid is working with Tree Data there is no need to explicitly specify a Group Column as the grid will use the
[Auto Group Column](./grouping-single-group-column/#group-column-configuration). However, you will probably want to
override some defaults as shown below:

```js {% frameworkTransform=true %}
const gridOptions = {
    autoGroupColumnDef: {
        headerName: "My Group",
        width: 300,
        cellRendererParams: {
            suppressCount: true
        }
    }
}
```

### Custom Column Group

As noted above, providing your own Custom Column Group has the advantage of giving you full control over the
presentation of the Column Group, however it is not as convenient as using the default Auto Column Group.

One significant difference is that the entire `dataPath` array will need to be supplied as a value, rather than just the current
node value.

For more details see [Custom Group Columns](./grouping-custom-group-columns/)

{% note %}
It is **not** possible to have multiple group display columns for tree data like you do for row grouping.
When using tree data, you should only have one column to display the group.
{% /note %}

## Example: Organisational Hierarchy

The following example combines all the steps above to show a simplified organisational hierarchy:

{% gridExampleRunner title="Org Hierarchy" name="org-hierarchy"  exampleHeight=525 /%}

## Filler Groups

It is not necessary to include entries for each level in the path if data is not required at each group level. Compare the two code snippets below:

```js
// all path levels provided
const rowData = [
    { filePath: ['Documents'] },
    { filePath: ['Documents', 'txt'] },
    { filePath: ['Documents', 'txt', 'notes.txt'], dateModified: "21 May 2017, 13:50", size: "14 KB" }
    ...
]

// only leaf level provided
const rowData = [
    { filePath: ['Documents', 'txt', 'notes.txt'], dateModified: "21 May 2017, 13:50", size: "14 KB" }
    ...
]
```

The second variation leaves out row data entries for 'Documents' and 'txt' nodes. In this case the grid will create `Filler Groups` for these.

This following example includes the column 'Group Type' to highlight which nodes are 'provided' in the row data and which are generated by the grid as a 'filler' group:

{% gridExampleRunner title="Filler Groups" name="filler-nodes"  exampleHeight=420 /%}

{% note %}
As `Filler Groups` are generated by the grid, they will not contain a `data` property on the `RowNode`.
This could be a limitation if you wanted to provide an 'id' for each group even when there is no data displayed at group levels or if you need to filter/sort the `Filler Groups`. In order to have filtering/sorting available on `Filler Groups`, you will need to provide all nodes as real nodes from your dataset, instead of using `Filler Groups`.
{% /note %}

## Tree Data Aggregation

When using Tree Data, columns defined with an aggregation function will always perform aggregations on the group nodes. This means any supplied group data will be ignored in favour of the aggregated values.

However if there are no child nodes to aggregate, the provided value in the row data will be displayed.

The [File Browser](#example-file-browser) example below demonstrates aggregation on the 'size' column. Note how the size provided in the data for 'Documents' is ignored and the aggregated value is used instead, whereas 'temp.txt' displays the provided size from the data as it has no children.

See [Aggregation](./aggregation/) for more details about group aggregation.

## File Browser Example

The following example is a more complex example that includes Aggregation:

* **'Add New Group' Button** - will add a new item in a new group under Music.
* **'Move Selected to stuff' Button** - will move any selected item and its children into the 'stuff' folder.
* **'Remove Selected' Button** - will remove selected item along with its children.
* **'Size' Aggregation** - as you move selected items into 'stuff' you'll notice updated folder sizes.

{% gridExampleRunner title="File Browser" name="file-browser"  exampleHeight=570 /%}

## Tree Data Filtering

As Tree Data has parent / child relationships, by default all child nodes will be included when a parent passes a filter. Filtering is additionally performed across all group levels. Therefore a group will be included if:

1. it has any children that pass the filter, or

1. it has a parent that passes the filter, or

1. its own data passes the filter

This can be seen in the [File Browser](#example-file-browser) example above, where the 'Files' column filter will filter group and leaf names across the entire file tree.

To disable Tree Data filtering and use regular filtering instead (which only shows groups where leaf children pass the filter), enable the following Grid Options property:

```js {% frameworkTransform=true %}
const gridOptions = {
    excludeChildrenWhenTreeDataFiltering: true,
}
```

Please note that Tree Data filtering behaves slightly differently to [Filtering Group Aggregations](./aggregation-filtering/#filtering-group-aggregations).

### Filtering Aggregated Parent Rows

The default behaviour of a group filter is to ignore aggregated group values that pass the filter, but this can be changed by enabling `groupAggFiltering`.

The default behaviour of a Tree Data filter is to match aggregated group values as well, and setting the `groupAggFiltering` property to `true` or `false` will not change this. The one exception is that the Set Filter will not match a value in a parent row when `groupAggFiltering` is `false`. You can also change this behaviour by using [Custom Group Aggregation Filtering](./aggregation-filtering/#custom-group-aggregation-filtering) because passing a function to the `groupAggFiltering` property will work the same as without Tree Data filtering.

### Aggregated Values Based on Pre-Filtered Data

The default behaviour of both Tree Data and group filters is to calculate aggregated values from the filtered results only. This can be changed by setting `suppressAggFilteredOnly = true`.

This behaviour can also be achieved in the Tree Data filter by setting `groupAggFiltering = true`.

As mentioned, if Tree Data filtering is disabled by setting `excludeChildrenWhenTreeDataFiltering = true`, then `groupAggFiltering` will work as normal.

The following example demonstrates aggregated values based on pre-filtered data by setting `groupAggFiltering = true`.

* Using the **Size** column apply a filter for the value **24.6**. Note that all results are displayed.
* Using the **Size** column apply a filter for the value **2.4**. Note that the 'cv.pdf' row and its parents are displayed. The value in the **Size** column for the 'Documents' parent row is **24.6 MB** (the pre-filtered value).

{% gridExampleRunner title="Aggregated Values Based on Pre-Filtered Data" name="group-agg-filtering"  exampleHeight=570 /%}

### Set Filter

When used with Tree Data, the [Set Filter](./filter-set/) will contain a list of all unique values across each level of the group hierarchy. The [File Browser](#example-file-browser) example above demonstrates how the Set Filter works with Tree Data.

It is also possible to display the Set Filter List as a [Set Filter Tree List](./filter-set-tree-list/), which replicates the Tree Data structure. This can be seen in the [Tree List](#tree-list-example) example below.

The Tree List also works with complex objects, which is demonstrated in the [Tree List Complex Objects Example](./filter-set-tree-list/#complex-objects).

The example below demonstrates using the Set Filter Tree List with Tree Data. Note the following:

1. The **Employee** group column has the Set Filter Tree List enabled via `filterParams.treeList = true`. A Key Creator is specified to convert the path into a string.
1. The Filter List displayed for the **Employee** column matches the format of the Tree Data structure.
1. The **Date** column has `filterParams.treeList = true` and is grouped by year -> month -> day.

{% gridExampleRunner title="Tree List" name="tree-list-filtering" /%}

## Pivot and Row Grouping with Tree Data

It is not possible to do pivot or row grouping while using tree data. This means that all the functions related to pivot (eg colDef.pivot, or pivot in the tool panel) and row grouping (eg colDef.rowGroup, or row group in the tool panel) will be disabled.

## Child Counts

If you are showing child counts for the groups, then the child count is a count of all children and grandchildren. This is different to [Row Grouping](./grouping/) where only leaf levels are counted; in tree data all group children are also counted.

## Selection

To enable selection set `gridOptions.rowSelection` to 'single' or 'multiple' as normal. However there are some restrictions to be aware of.

### Checkbox vs Click Selection

Click selection is supported with tree data. However when you are displaying tree data, clicking rows for selection is confusing as mouse clicks are also used for expanding / contracting rows. For this reason we recommend not using click selection and using checkbox selection instead.

```js {% frameworkTransform=true spaceBetweenProperties=true %}
const gridOptions = {
    // don't have click select rows
    suppressRowClickSelection: true,

    // have checkbox on the group column
    autoGroupColumnDef: {
        cellRendererParams: {
            checkbox: true,
        }
    }
}
```

### Group Selection

[Filler Groups](#filler-groups) do not keep their selection state should the filler group be moved. For example if you have groups A->B->C, where C is the only row provided (so the grid creates groups A and B for you), and then you change the path to D->B->C, group B will not keep its selection.

If keeping selection of groups is a priority, then arrange your data so that the grid does not need to create any filler groups.

### Example: Selecting Groups and Children

Below is an example demonstrating the property `groupSelectsChildren` used with tree data.

In the example below, note the following:

* Selecting all child rows will select the parent
* Selecting only some children will mark the parents as partially selected
* Selecting a row, and then selecting another while holding the shift key will select all rows between the two rows
* Selecting a parent will also select all of its children

{% gridExampleRunner title="Group Selects Children" name="group-selects-children"  exampleHeight=525 /%}

## Next Up

Continue to the next section to learn about [Pivoting](./pivoting/).
